BigDFT.Systems module

This module contains the System level class of PyBigDFT. Systems are named collections of fragments, and represent a complete system for simulation.

class FragmentView(purities, bond_orders, charges)[source]

Bases: object

The representation of a system in terms of fragments and groups of superunits.

Parameters
  • purities (dict) – dictionary of the purities of the system

  • bond_order (dict) – double dictionary of the bond orders of the superunits

  • charges (dict) – dictionary of the number of the electrons of the superunits

refragment(mapping)[source]
remove_fragment(fragid)[source]

Remove a particular fragment from this view.

Parameters

fragid (str) – the id of the fragment to remove.

GetFragId(atdict, iat)[source]

Obtain the fragment identifications from the atom description

Parameters
  • atdict (dict) – dictionary of the atom

  • iat (int) – position of the atom in the list

Returns

fragment_id

Return type

str

GetFragTuple(fragid)[source]

Fragment ids should have the form: “NAME:NUMBER” or “NAME-NUMBER”. This splits the fragment into the name and number value.

Parameters

fragid (str) – the fragment id string.

Returns

fragment name, fragment number

Return type

(tuple)

class Lattice(vectors)[source]

Bases: object

Defines the fundamental objects to deal with periodic systems

grid(origin=[0.0, 0.0, 0.0], extremes=None, radius=None)[source]

Produces a set of translation vectors from a given origin

class System(*args, **kwargs)[source]

Bases: collections.abc.MutableMapping

A system is defined as a named collection of fragments. You can manipulate a system as if it were a standard python dictionary, however it also has helper routines for performing operations on the full system.

property PointParticles

~PointParticles.PointParticles` object

Type

Transform the system into a `py

Type

class

ase_potential_energy(ase_calculator)[source]

Given a ASE calculator, calculates the potential energy of the system.

Parameters

ase_calculator (ase.calculators.calculator.Calculator) – ASE calculator.

Returns

the potential energy, in Hartree

Return type

float

property central_fragment

Returns the fragment whose center of mass is closest to the centroid

Returns

the name of the fragment. (Fragment): the fragment object

Return type

(str)

property centroid

Center of mass of the system

compute_matching(atlist, check_matching=True)[source]

Frequently we are passed a list of atom like objects from which we need to extract data and assign it to a system. However, a system can potentially store those atoms in any order, and may not have the same set of atoms. This helper routine creates a mapping between this list view, to the dictionary view of the system class.

Parameters
  • atlist (list) – a list of atom like objects.

  • check_matching (bool) – if set to True, this will raise an error if we can’t match all of the atoms in the system.

Returns

a mapping from a system to indices in the atom list. If

an atom is not in the list, an index value of -1 is assigned.

Return type

(dict)

dataframe_slicing(df=None)[source]

Define a dictionaries of two-element lists indicating the slicing (start and end points) of the corresponding fragment in the order provided by the dataframe

Parameters

df (Dataframe) – associated to the system

Returns

dictionary of the slicings of the fragments in the dataframe

Return type

dict

property df
dict()[source]

Convert to a dictionary.

display(colordict=None, field_vals=None, cartoon=False)[source]

Display the system using the inline visualizer of Py3DMol

distances_from_target(target)[source]

Provide the dictionary of the distances from a target.

Parameters

target (list) – list of the fragments identifying the target.

Returns

dictionary of the minimum distance from the target per frag.

Returns 0 if the fragment belongs to the target.

Return type

dict

property electrostatic_interactions

Dictionary of the Electrostatic interactions between fragments.

examine(axs=None, view=None)[source]

Provide quick overview of the system’s quality.

This routine displays information about the coordination numbers and the bond of the system. Useful to understand if some positions of the system need optimization.

Parameters
  • axs – list of matplotlib axis in which to plot the information. If the forces are present it should be of size 3.

  • view (dict) – a Fragment view of the system in which to represent the fragment forces. If absent, the fragment forces are not represented.

Returns

Dictionary of the information about the system

Return type

dict

get_external_potential(units='bohr', charge_offset=False)[source]

Transform the system information into a dictionary ready to be put as an external potential.

Parameters
  • units (str) – the units of the external potential.

  • charge_offset (bool) – by default the external potential ignores the counter charge from the protons. Setting this to true adds the positive charge to the potential.

get_k_nearest_fragments(target, k, cutoff=None, return_type='list')[source]

Given a fragment id in a system, this computes the nearest fragment.

Parameters
  • target (str) – the fragment to find the nearest neighbor of.

  • k (int) – the number of fragments to look for.

  • cutoff (float) – will only return fragments with a certain cutoff.

  • return_type (str) – ‘list’ or ‘dict’

Returns

the ids of the nearest fragments, or their distances

as values in the case in which ‘dict’ is provided in the return_type argument

Return type

(list, dict)

get_nearest_fragment(target)[source]

Given a fragment id in a system, this computes the nearest fragment.

Parameters

target (str) – the fragment to find the nearest neighbor of.

Returns

the id of the nearest fragment.

Return type

(str)

get_net_force()[source]

Returns the net force on a system in Ha/Bohr.

Returns

Three values which describe the net force.

Return type

(list)

get_posinp(units='angstroem')[source]

Provide the dictionary which has to be passed to the posinp value of the run() method of the SystemCalculator class instance.

Parameters

units (str) – The units of the file.

property q0

Provides the global monopole of the system given as a sum of the monopoles of the atoms.

property qcharge

The total qcharge of a system.

reform_superunits(mapping)[source]

Creates a new system from the provided mapping

Parameters

mapping (dict) – dictionary of the form {newfrag: [frag1,frag2]} defining the mapping between the old fragments and the new

Returns

a new system from the remapping

Return type

BigDFT.Systems.System

rename_fragments(fragment_mapping=None)[source]

This procedure automatically names the fragments in a system.

Parameters

fragment_mapping (dict) – Dictionary containing list of fragments that are additionally added to each of the original system’s fragments.

Returns

the same system, with the automatic naming scheme.

Return type

BigDFT.Systems.System

serialize(order=None, units='bohr')[source]

Transform the system in a list that can be employed for the construction of dataframes or pandas series. :param order: list of fragments to serialize in order :type order: list :param units: the units for the positions :type units: str

Returns

the serialized system as well as a lookup dictionary

that contains the order of the fragment atoms in the series

Return type

list

set_atom_forces(logfile)[source]

After a run is completed, we have the forces on each atom in the logfile. This routine will set those values to each atom in this sytem.

Parameters

logfile (Logfiles.Logfile) – logfile with the forces.

set_atom_multipoles(logfile, correct_charge=True)[source]

After a run is completed, we have a set of multipoles defined on each atom. This routine will set those values on to each atom in the system.

Parameters
  • logfile (Logfiles.Logfile) – logfile with the multipole values.

  • correct_charge (bool) – currently there is an inconsistency in terms of gross charge, and this corrects it.

set_electrons_from_log(log)[source]

BigDFT uses pseudopotentials, so this will extract from a logfile the number of actual electrons modelled for each atom in the system.

Parameters

log (Logfiles.Logfile) – A BigDFT run logfile.

set_logfile_info(log)[source]

Include the information of the logfile in the fragment quantities.

Parameters

log (Logfiles.Logfile) – A BigDFT run logfile.

subsystem(fragments)[source]

Extract a subsystem.

Create a subsystem from a collection of fragments.

Parameters

fragments (list) – the list of the original fragments which have to be inserted in the new system

Returns

a new System class instance. The reference fragments are

shallow-copied.

Return type

System

to_dataframe(**kwargs)[source]

Convert the system into a dataframe, from the py:meth:~System.serialize method.

Parameters

**kwargs – arguments to be passed to py:meth:System.serialize method

update_positions_from_dict(posinp)[source]

Update the atomic positions of a system from a posinp dictionary.

This method only works if the order of atoms match.

Parameters

posinp (dict) – a posinp dictionary.

atom_slicing(sl, fragments)[source]

Slicing of the atoms of the provided fragment list.

check_slicing(system, slicing)[source]

Assert the validity of a system’s slicing

copy_bonding_information(sys1, sys2)[source]

This routine will take the bonding information of sys1 and copy it over to sys2. This routine requires that both systems have the exact same atoms in them. This is useful if you refragment a system and want to fix the bonding information.

Parameters
df_fragment_forces(df)[source]
distance_matrix(sys, ref)[source]

Calculate a distance descriptor between a system and a reference.

examine_system_dataframe(df, dist=None, view=None, fragment_forces=None)[source]
fragment_slicing_from_system_dataframe(df)[source]

Define the slicing tuple needed to identify the fragment blocks into a system dataframe

Parameters

df (Dataframe) – the system dataframe

Returns

dictionary of the slicing obtained in form of [start,end] list

Return type

dict

lineup_system(sys)[source]

Align the principal axis of inertia of a system along the coordinate axis. Also shift the system such as its centroid is zero.

Parameters

(BigDFT.Systems.System) – the system to transform.

Returns

the transformed system.

Return type

(BigDFT.Systems.System)

plot_fragment_information(axs, datadict, colordict=None)[source]

Often times we want to plot measures related to the different fragments in a system. For this routine, you can pass a dictionary mapping fragment ids to some kind of value. This routine takes care of the formatting of the axis to easily read the different fragment names.

Parameters
  • axs (matplotlib.Axes) – an axes object to plot on.

  • datadict (dict) – a dictionary from fragment ids to some kind of data value.

  • colordict (dict) – optionally, a dictionary from fragment ids to a color value.

point_particle_objects(df)[source]

Return the dictionary of the point particle quantities from a Systems’ dataframe

select_from_view(view, targets)[source]

Identify the fragments of the view that contain at least one of the targets

Parameters
  • view (dict) – if present, identifies the fragments that contain the relevant units

  • targets (list) – list of the fragments to search in the view

Returns

fragments to select

Return type

list

system_from_df(df)[source]

System instance from system dataframe.

Returns a System from a dataframe. Useful to reconstruct a dataframe-serialized system in case one needs to extract quantities of relevance.

Parameters

df (pandas.DataFrame) – the System Dataframe as returned usually from py:func:System.df property.

Returns

the instance derived from the dataframe.

Return type

System

system_from_dict_positions(posinp, units='angstroem')[source]

Build a system from a set of positions from a dictionary whose yaml serialisation is compliant with the BigDFT yaml position format

Parameters

posinp (list) – list of the atomic specifications

Returns

an instance of the system class.

The employed fragment specification is specified in the file.

Return type

BigDFT.Systems.System

system_from_log(log, fragmentation=None)[source]

This function returns a System class out of a logfile. If the logfile contains information about fragmentation and atomic multipoles, then the system is created accordingly. Otherwise, the fragmentation scheme is determined by the fragmentation variable.

Parameters
  • log (Logfile) – the logfile of the QM run. In general must have been done with Linear Scaling formalism.

  • fragmentation (str) – the scheme to be used for the fragmentation in the case if not provided internally by the logfile. The possible values are atomic and full, in which case the system as as many fragments as the number of atoms, or only one fragment, respectively.

Returns

The instance of the class containing fragments.

Return type

(BigDFT.Systems.System)

update_purity_and_bo(mapping, purity, bo, charges)[source]

When merging fragments together, you will need to update the bond orders and purity values. This can be done by using run_compute_purity and compute_bond_orders, but this process is potentially slow. In this function, we use the old bond orders and purity values for update, which is much faster.

Parameters
  • mapping (dict) – a dictionary where the keys are the new fragments and the values are a list of old fragments that make up this new fragment.

  • purity (dict) – the old purity values of each fragment.

  • bo (dict) – the old bond orders of each fragment.

  • charges (dict) – the charges of each fragment (the sum of the number of electrons).

Returns

the new purity and bond order values.

Return type

(dict, dict)

validate_dataframe_representation(sys, df)[source]

Control if the units of the positions in the dataframe are in Bohr. Update the coordinate values if this is not so.

Parameters
  • sys (BigDFT.System) – System which provides the reference positions

  • df (pandas.DataFrame) – system’s dataframe

BigDFT.Systems example

Below we show an example of using the system class.

def _example():
    """Example of using a system"""
    from BigDFT.IO import XYZReader
    from BigDFT.Fragments import Fragment

    safe_print("Read in some files for the fragments..")
    reader = XYZReader("SiO")
    frag1 = Fragment(xyzfile=reader)
    reader = XYZReader("Si4")
    frag2 = Fragment(xyzfile=reader)

    safe_print("Now we move on to testing the system class.")
    sys = System(frag1=frag1, frag2=frag2)
    for at in sys["frag1"]:
        safe_print(dict(at))
    for at in sys["frag2"]:
        safe_print(dict(at))
    safe_print()

    safe_print("What if we want to combine two fragments together?")
    sys["frag1"] += sys.pop("frag2")
    for at in sys["frag1"]:
        safe_print(dict(at))
    safe_print("frag2" in sys)
    safe_print()

    safe_print("What if I want to split a fragment by atom indices?")
    temp_frag = sys.pop("frag1")
    sys["frag1"], sys["frag2"] = temp_frag[0:3], temp_frag[3:]
    for at in sys["frag1"]:
        safe_print(dict(at))
    for at in sys["frag2"]:
        safe_print(dict(at))
    safe_print()